General notes
-------------

Sorry - not much documentation yet.  Maybe next release. 

The actual library is file Utils.  The rest is sources, headers etc. 
The makefile is suitable for use with Amu or !Make. The file GMakefile
is a makefile for my port of Unix Gnu Make, which should be available
on various BBSs - otherwise it is on one of David Pilling's disks -
sorry but I forget which.  See his ads.

However, all should become clear if you look at the sources or the
header files.  Most stuff is fairly simple and/or implementations of
Unix stuff.

Most of this is tested fairly thoroughly (particularly the Unix-like
stuff - I use it all the time!) but the more obscure stuff such as the
data structures - stack, queue, etc - are probably less robust.

Some parts of this package are not my own work. They are PD routines
which I have found sufficiently useful to want to incorporate in this
library. I take NO credit for anything good in these routines. The
errors and mistakes, however, are most likely caused by me changing
things to conform to the "style" of this library. My thanks go to the
authors of these routines, for making them PD.

Specifically, the parts I did not write are:
	The execution profiler, by Ferdinand Oeinck.
	The regular expression routines, by the Free Software Foundation.
	The option parser (getopt), by the Free Software Foundation.
	The coroutine handler, by David McQuillan.
	The swi veneers, by Edward Nevill.
In the case of the profiler (in subdirectory Profile), coroutine (in
file C.Coroutines) and swi (in files S.Swi and H.Swi) routines, I have
made very few changes beyond any reformatting. The sources here should
be largely complete. The two FSF packages - options (in directory Getopt)
and regular expressions (in directory Regex) - have been hacked about, on
the other hand. In the case of getopt, the changes are fairly small, but
in the case of regex, I have done some massive "streamlining", plus a few
changes to the RE syntax accepted (to standardise the RE syntax accepted
across all my Arc ports. The resulting syntax is based on perl).

Enjoy!

Gustav (pmoore@cix.compulink.co.uk)

---------------------------------------------------------------------------

The filter package
------------------

These functions (source in C.Filter) implement "filters", which
basically simulate Unix pipes. What you do is, you create a filter as

     FILTER *f = FLTopen();

and then shove data into it using the (FILE *) FLTin(f). This is a
file handle which has been opened for writing by the FLTopen().

Once you've finished writing data in, you can pass it through a set
of commands by simply typing

     FLTfilter(f,command);

This returns a return code, or -2 (FILTER_ERROR) if an error occurred.
Assuming everything went OK, you can read the output on the file pointer
FLTout(f), and then execute another FLTfilter() - or you can just go
straight on to the next command.

When you've finished, use FLTclose(f) to close the filter and tidy up (ie
close files, and remove temporary files).

FLTfilter assumes all commands conform to C redirection specifications
(in other words they use < and > to redirect stdin and stdout), except
for a set list of builtin commands (see the file C.OsCmd - I basically
just did a *HELP on my machine). Alternatively, starting any command
with a % forces it to be treated as a builtin, and the % is ignored.
Builtins are redirected using { < ... } and { > ... }, and the output
file is post-processed to remove all the extra CRs which are generated.

It would be fairly simple with these functions to build a *PIPE command, say

     *PIPE cmd1 <in | cmd2 -o -x | cmd3 >out

I'll probably do so one day...

They are also used in the EMACS (C-X !), (C-X @) and (C-X #) commands.

---------------------------------------------------------------------------
